How To Ask Questions

From OSDev Wiki
Jump to navigation Jump to search

These are a few hints for the first-timers and other newbies to maximize your chances of getting a useful answer to your question and have the community pleased to help you rather than annoyed by your complaints. It has been inspired by the How To Ask Questions The Smart Way document which you can easily retrieve with a web (Google) search. The guide here is only the subset of the "official" document by Eric S. Raymond that applies to web fora (and this forum in particular).

Note: While it should be obvious, it nonetheless comes up often enough that it needs to be said - Eric S. Raymond and Rick Moen should never be directly contacted for assistance with any software project which they are not personally involved in! The very fact that this occurs at all indicates that the readers of sites like this have not read and understood their recommendations. Since the authors have specifically asked that this warning be included with any link to their document, it needs to be emphasized at every possible opportunity.

Identification and User Accounts

Take the time to set up a user account up front, with a recognizable user name and avatar. Trying to figure out if "aetroi" is the same guy as "sdfoiu" based on the problem description and IP address will lead to the same questions asked again and again. Your user account gives us a way to contact you in private, sending replies by e-mail if we feel the response would be off-topic or too long. A unique avatar helps recognizing your posts at one glance.

Note: Registration on the OSDev.org forums is compulsory. As a benefit of registration, you can also register to get wiki edit access.

Title

This helps us identifying subjects we know about. "Kernel Question" is a bad thread title. "IVT Question" is a marginally better thread title. "Interrupt Handler Triple-Fault on Mouse Movement" is an excellent thread title. A lot of the forum regulars do not read every topic; forum traffic has now increased to the point where this is almost impossible (especially in the OS Development subforum). A good title will grab attention from the people who do know the topic.

Grammar

Bad grammar, spelling and/or punctuation makes your post much harder to understand. You will end up with people either ignoring your post or debugging your language instead of debugging your problem. Stay away from 1337 and SMS shortcuts, too. Basically, use proper English (whether that happens to be UK or US spelling is largely irrelevant).

As a side note, the OSDev.org forums do not currently have any subfora for languages other than English. This is deliberate. Splitting the forums up more means less people will read and be able to answer to each topic. Eric S. Raymond has also made the point that programming in general (and OS development in particular) is a topic with so many English words used that it is easier to communicate in English anyway.

Programming Background

OS development is not a reasonable place to learn how to program in C, Assembly, or any other language, something that is pointed both in this wiki and in the forum rules. These warnings are there for a reason, and asking a question that indicates to us that either you didn't read and understand those rules, or chose to ignore them, is unlikely to garner much sympathy here.

It is true that the OS development fora have a reputation for being harsh towards newbies. There's a reason for this: OS development isn't a topic that a newly-minted programmer can reasonably approach. A lot of people jump into the field too early - before they have the background and experience to really understand what they are doing - and get burned by their lack of preparedness. Unfortunately, this leads to us seeing a lot of the same mistakes and problems again and again, ones which could be avoided if the poster had simply read those warnings and followed their advice.

This is not a field that you can learn through simple tutorials, especially if you're do nothing but copying and pasting the tutorial code and trying to make it work without understanding it. The tutorials that do exist - and for most subjects in this area, there aren't any, and their cannot reasonably be any - are meant as guidelines, not cookbooks. Cutting and pasting code out of several different existing sources and expecting them to magically fit together is simply an unworkable approach to OS development. You will need to learn a lot, and thoroughly understand what you are doing, before you can expect to approach this field in a meaningful manner.

Research

The wiki is constantly extended and revised. The chances are good that the answer to your question is already in there. This is especially true if you are having problems early on in the development cycle: topics such as Interrupts, setting up a GCC Cross-Compiler and Printing to Screen have huge amounts of information already in the wiki.

If you are using one of the more common tutorials/sample kernels your question is probably already answered in the forum. Use the forum search function and the answer will await.

If your question is "where can I find X", or "are there any programs that do Y", a search engine will almost certainly give you a faster, and possibly even better-informed answer than we here.

It is quite common to stick with a solution once you found one - many people around here could point you to one or two options, but might be missing the very one that would suit you best.

You're less likely to get the response you were looking for by asking general questions like "how do I read from a FAT disk?", "how do I load program?", or "are there any memory management tutorials?" Asking such questions shows a lack of an essential programming skill; a programmer should able to solve problems by him/her self, and is a clear indication that one has not done their research. A better example could be rephrasing the question as "I am trying to do X. I have done Y, but I do not fully understand Z."

Regarding Outdated or Incomplete Wiki Articles

It is a sad truth of any large collaborative project such as a wiki that inevitably, some information becomes outdated without it being noticed. Just as inevitably, some subjects simply don't get the attention they need. If you notice something where you think this has happened, please try not to get angry; instead, politely bring it up on the message board, so someone - possibly yourself - can add to it and/or update it.

It may be that it was simply missed until now, or that no subject-matter expert had addressed it yet; it may also be that someone has hoisted a copy of the page to their own private pages in order to do a major overhaul, which isn't reflected in the official page yet. It could even be that there is contention over how to address the topic, which has delayed planned updates. Conversely, it may be that you missed something somewhere else (which can certainly happen, given the size and sprawl of the wiki), and forum-goers familiar with the topic can point you in the right direction. In either case, it would be better to be constructive and pro-active rather than flaming about it.

Details

OS code is highly interdependent. If you give us only the source code for the interrupt handler that tripple-faults, we will be unable to find the bug in your IVT setup that actually causes the error. We also need to know what compiler / assembler / linker you are using, in which version, and which command line options you are using.

Creating an entry describing your project and environment in the OS Projects list, and adding a link to that entry to your forum signature, will also allow us to quickly get answers to trivial questions such as "what compiler do you use?" or "what's your development environment?" or "are you using GRUB? Bochs? VMware?" etc.

Just as giving too little information, too much can be just as harmful. It is easy to give the wrong impression ("I have a problem, but cannot be bothered to narrow it down. Fix it for me!").

While your project structure might be completely logical and intuitive for you, others might still be confused, and no-one likes digging through several dozen source files to find out what's happening.

Try to find a minimum code subset sufficient to reproduce the problem. (That's also a good debug technique; you might locate the error yourself in the process.)

As always, one key component of any OS project should be an off-site source control repository; in addition to the advantages regarding code retention and backup, it allows responders to view the code in question without having to either wade through a large code post, or have to ask for the code to be posted over and over again. If you have such a repository (and you should), be certain to include a link to the location of the code section you are having trouble with. This will allow the forum-goers to see the latest version of the code, and refer to it directly. As already stated, you should limit code posts to exactly that part of the code that you are having problems with; if the problem proves to be elsewhere, the repo should permit that to be determined over time.

Formatting

The forum has a [code] ... [/code] formatting command that you can use to highlight your code snippets and avoid smilies/fontifying tags to mess up your post.

Split your post in paragraphs of a few sentences. Do not shout (e.g. WRITING IN CAPITALS) or use nifty but useless formatting (like glowing colored fonts, moving text, lines of smilies etc.). Use the 'preview' feature if possible.


Describing Goals

When one is working a particular problem X, it is not uncommon to find a solution Y which looks to be a suitable, but which you don't know how to implement correctly, or have problems debugging. This may lead you to post a question on how to do Y correctly. This is fine, except that doing so without explaining the context (problem X) of why you want to solve problem Y may lead to answers which solve Y, but not in a way that solves X. Indeed, it may be that Y doesn't solve X at all, or that there is a significantly better solution to X which you aren't aware of. In this case, asking about Y is going to lead you down a blind alley. At best, it may leave those who could reply confused as to your goal, causing them not to reply at all even if they might actually know how to solve X.

This sort of false solution is known as the XY Problem (or more humorously, a 'Bottle or Old Shoe' Question), which is one of the most frustrating communication problems one can have on a forum.

In order to avoid this, you should carefully consider whether you have explained enough about what you are trying to accomplish when asking for help. You don't need to give a detailed account of your project, but a thumbnail sketch of the immediate goal (and any solutions to it you have used in the past) can go a long way in setting up enough context for the respondents to knowledgeably answer your question.

Identifying the Problem and Describing it to Others

Try to isolate your problem as far as you can before posting about it, and give as much information as you can in your post. Both too little information, and too much, make it harder to answer the questions, but in general too much is better than too little.

When asking for programming help in general, it is usually advisable to give a Short, Self Contained, Correct (Compilable), Example, isolated from the actual codebase. However, in OS Dev, this may not be possible, as bugs are often closely tied to the overall environment, and in any case isolating code for kernel or driver operations may not be possible. If you can give one - even if it requires some additional scaffolding - then do so, as it will go far in isolating the issue from extraneous details, but we won't fault you if you can't (though we might if you won't, as it is rude not to at least try).

Posting Code Samples versus Linking to a Repository

In explaining a problem it is likely that you will need to provide either code samples of the problem section(s), or a link to your code repository, or both. In general, when posting code samples, you want to give enough code to illustrate the problem, and no more. Just how much that is can be difficult to judge, however. Also, extremely long code samples tend to be hard to read through in a post, so if you have more than (say) 50 lines of code in a snippet, it may be better to link to it instead. Even with a smaller snippet, including a link to your repo is appreciated, as it may allow us to get some additional context for the issue.

Note that posting code, or a repo link, and telling us 'this doesn't work' is not sufficient. It is extremely rude to simply give a large code sample or a link to a repo and expect us to answer your problem without at least telling us where in the codebase you think the problem lies. Doing so without explaining the failure mode (i.e., what is or isn't happening) is even more so. One would think this wouldn't need to be said, but apparently it does.


Following above guidelines significantly improves your chances to get a quick and helpful reply. (And it makes helping you more fun, so those with the know-how will stick around and still be available to help you tomorrow.)